.\" $Coar$
.\" ldapform: prepare an LDIF form to update a given ldap entry.
.\" %%LICENSE%%
.Dd Jan, 04 2012
.Dt LDAPFORM 1
.Os
.Sh NAME
.Nm ldapform
.Nd prepare an LDIF form to update a given ldap entry.
.Sh SYNOPSIS
.Nm
.Bq options
.Ar filter
.Nm
.Fl e
.Bq options
.Ar filter
.Nm ldapedit
.Bq options
.Ar filter
.Sh DESCRIPTION
The
.Nm ldapform
utility creates a text file in
.Xr ldif 5
format, which can be used to add or modify entries in an LDAP server. The
.Nm ldapedit
utility does the same, but also submits the changes back to that server.
.Pp
Both utilities require read access to operational attributes of the top
level subschema to obtain the objectclass and attribute definitions.
This means that the authorized user should be able to get the info using
the following command:
.Dl % ldapsearch [authopts] -b cn=Subschema -s base '(objectClass=*)' +
If the above fails, check your ACLs.
.Sh OPTIONS
.Bl -tag -width indent
.It Fl b Ar base
Specify the search base for the
.Ar filter .
.It Fl C
Use compact format. See
.Sx FORMATS
below.
.It Fl D Ar dn
Specify the distinguished name of the authenticating user for simple binds.
.It Fl f Ar file
Write output to
.Ar file .
When in edit mode, this flag will use 
.Ar file
instead of a temporary file and the file will not be removed when submitted
to the server.
.It Fl H Ar uri
Specify the URI of the ldap server. The options
.Fl h
and
.Fl p
are ignored when using this option.
.It Fl h Ar hostname
Specify the hostname of the ldap server. If a uri is also specified (see
.Fl H )
this option is ignored.
.It Fl O Ar props
Specify security properties for SASL authentication as a comma-separated
list. Refer to SASL_SECPROPS in 
.Xr ldap.conf 5
for more information.
.It Fl p Ar port
Specify the port to connect to. Default: 389. This option is ignored if
.Fl H
is set.
.It Fl R Ar realm
Specify the realm for SASL authentication.
.It Fl s Ar scope
Specify the search scope for the
.Ar filter .
Can be one of
.Bl -ohang -offset indent
.It Sy base
Search base only.
.It Sy one
One level.
.It Sy sub
Base and all descendants (subtree).
.It Sy children
Children only. Requires LDAPv3 subordinate feature extension.
.El
.It Fl U Ar authcid
Authentication ID for SASL authentication.
.It Fl v Op v
Increase verbosity. When specified twice, trace information will be printed.
.It Fl W
Prompt for password when using simple binds. Will fail if not using a tty,
use
.Fl y
instead.
.It Fl w Ar password
Specify the password for simple binds.
.It Fl X Ar authzid
Authorization ID for SASL authentication if different from
.Ar authcid
.It Fl x
Use simple binds.
.It Fl Y Ar mech
Specify the SASL authentication mechanism.
.It Fl y Ar pwfile
Specify the file containing the password for simple binds. Use
.Sq "-"
for stdin.
.It Fl Z Op Z
Use the START TLS LDAP operation on a normal connection. If used twice,
require it to succeed.
.El
.Sh FORMATS
Standard format is meant for modifications. For each matching entry, a
.Sq "changetype"
attribute is printed. For each
.Sq objectClass
attribute a
.Sq delete
attribute is printed. For all other attributes, an
.Sq add
and
.Sq delete
attribute are printed, along with the attribute and it's value (if available).
Each attribute is continued properly with a dash on a line by itself.
.Pp
Compact format is meant for additions. For each matching entry all attributes
are printed with it's value (if available). This makes it easier to copy an
entry to a different entry.
Both formats preceed an attribute section with a comment describing the
attribute, if one is available in the schema definition as stored by the
server.
.Sh DIAGNOSTICS
.Bl -diag
.It EX_USAGE
Unknown option or using invalid combination of options.
.It EX_OSERR
Failed memory allocations or failed syscalls that should not be failing.
.It EX_UNAVAILABLE
Connection to the LDAP server or TLS negotiation failed. Diagnostics are
printed on stderr.
.It EX_CANTCREAT
The
.Ar file
argument to the
.Fl f
option cannot be created.
.It EX_NOINPUT
Passphrase can't be read when
.Fl W
option is used or no entries matched the supplied
.Ar filter .
.It EX_DATAERR
Environment variable(s) contain incorrect data or the form submitted back
to the server has invalid syntax.
.It EX_PROTOCOL
Invalid syntax in one of the server stored schemas (should never happen and
as such indicates corruption on the wire) or the search query cannot be
completed.
.It EX_NOPERM
Operational attributes cannot be fetched. Most likely cause being server-side
ACL's.
.It EX_OK
All went well.
.El
.Sh FILES
The following files work as described in
.Xr ldap.conf 5 :
.Bl -tag -width ".Pa /usr/local/etc/openldap/ldap.conf" -compact
.It Pa /usr/local/etc/openldap/ldap.conf
.It Pa ~/.ldaprc
.It Pa ./.ldaprc
.El
.Sh ENVIRONMENT
The variables
.Ev LDAPRC
and
.Ev LDAPCONF
work as described in
.Xr ldap.conf 5 .
Additionally, the variables
.Ev LDAP_USE_TLS and
.Ev LDAP_REQUIRE_TLS
work as
.Fl Z
and
.Fl ZZ
respectively. That is, when set they activate and may require TLS. These do not work for Openldap supplied tools.
When using editmode, the preferred editor is taken from
.Ev EDITOR .
If unset,
.Xr vi 1
is used.
.Sh BUGS
.Bl -bullet -offset indent
.It
SASL authentication is untested and may not work.
.It
Edit mode is currently non existent.
.It
If TLS negotiation fails, so will simple binds. As such, the net effect of
.Fl Z
and
.Fl ZZ
are identical. However, compatibility with Openldap tools is kept.
.It
Portability framework not in place yet, so either have FreeBSD compatible
interfaces available or use a VM.
.El
.Sh SEE ALSO
.Xr ldapsearch 1 ,
.Xr ldapmodify 1 ,
.Xr ldif 5 ,
.Xr ldap.conf 5
